Configuration items
This section describes what configuration items are, how to edit configuration items, and the configuration options that are available to you.
Configuration items overview
During installation, configuration items are created on the host system. Configuration changes are made by editing the values associated with these items. This chapter describes how to make such changes on your system.
Item values can exist at four configuration levels. When a configuration item is queried, item locations are searched in order of level precedence:
-
Temporary: Any changes made at the temporary configuration level override any corresponding entries at the user, system, and default levels.
-
User: Changes made at the user level override any corresponding entries at the system and default levels.
-
System: System changes override default-level entries.
-
Default: If no changes have been made at any other level, the default value for the configuration item is used. Default configuration values cannot be changed.
On Windows operating systems, user and system configuration information is stored in the Registry. On Unix-based systems, configuration files are used. Temporary configuration items are applied using environment variables on both Windows and Unix-based platforms.
Regardless of the platform, a common naming convention for configuration items has been followed. Understanding this naming convention will help you locate and change the appropriate configuration items when required.
Configuration items are hierarchical in structure, with the root node ET. Child nodes of the root represent the class of the item, and are typically product abbreviations, such as PTKC (ProtectToolkit-C) or HSM (Hardware Security Module). Nodes under class represent the component, such as LOGGER or SMS. Finally, nodes under component represent the configuration item, such as FILE, MODE, or NAME. Configuration items therefore take the form:
ET_<class>_<component>_<item>
Editing configuration items
The procedure for editing configuration items is different for ProtectServer 3 External HSMs, client machines, and systems hosting ProtectServer 3 PCIe HSMs.
Select the procedure that is relevant to your deployment.
Client/PCIe HSM server configuration
The procedure for configuring client/PCIe HSM host systems differs between Windows and Linux. Please refer to the relevant section below.
Temporary
Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical, the hierarchy is implicitly defined by the name of the variable.
In Network mode, to temporarily change the length of time the HSM will wait before timing out a connection attempt
In a command prompt, enter set ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS=<time_in_seconds>
User
User configuration changes are made in the registry tree starting from HKEY_CURRENT_USER\SOFTWARE\SafeNet.
In Network mode, to change the length of time the HSM will wait before timing out a connection attempt
-
Open regedit to HKEY_CURRENT_USER\SOFTWARE\SafeNet.
-
Add a new key entitled HSM and open it.
-
Add a new key entitled NETCLIENT and open it.
-
Add a new string named ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS.
-
Set the value data to the desired time in seconds.
System
System configuration changes are made in the registry tree starting from HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet.
The name of the ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the Windows registry as a string value for the entry:
ET_PTKC_LOGGER_FILE
This is located in the key:
HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\PTKC\LOGGER
Temporary
Temporary configuration changes are made using environment variables. Since environment variables are not hierarchical in nature, the hierarchy is implicitly defined by the name of the variable.
User
User Configuration is a set of files located in the $HOME/.safenet directory.
System
System Configuration is a set of files located in the /etc/default directory.
The User and System Configuration files are of the form: et_<class>. Entries in the file are of the form:
ET_<class>_<component>_<item>=<value>
The name of the ProtectToolkit-C file where the logger library writes log information (ctlog.log) is stored in the /etc/default/et_ptkc file as the entry:
ET_PTKC_LOGGER_FILE=/ctlog.log
ProtectServer 3 External server configuration
Server configuration settings on the ProtectServer 3 External are edited by transferring a new configuration file to the appliance, and applying it using PSESH. This procedure must be completed by the pseoperator.
To change the ProtectServer 3 External server configuration
-
Create a text file on your client machine that lists each configuration item and its desired value. For a list of editable configuration items and their valid values, see Network Mode Server Configuration Items.
For example:
ET_HSM_NETSERVER_OLD_WORKER_COUNT=5 ET_HSM_NETSERVER_V2_WORKER_COUNT=12 ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40 ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40 ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5 ET_HSM_NETSERVER_FRAG_SIZE=5000 ET_HSM_NETSERVER_ALLOW_RESET=OnHalt ET_HSM_NETSERVER_PORT=12396 ET_HSM_NETSERVER_LOG_CHANNEL=0 ET_HSM_NETSERVER_LOG_NAME=etnetserver ET_HSM_NETSERVER_LOG_LEVEL=0 -
Transfer the configuration file (et_hsm.txt in the example below) to the pseoperator user on the appliance using pscp (Windows) or scp (Unix/Linux):
pscp -scp <filename> pseoperator@<server_host/IP>:<filename>
pscp -scp et_hsm.txt admin@192.168.0.123:et_hsm.txt pseoperator@192.168.0.123's password: ******** et_hsm.txt | 0 kB | 0.4 kB/s | ETA: 00:00:00 | 100%scp <filename> pseoperator@<server_host/IP>:<filename>
scp et_hsm.txt admin@192.168.0.123:et_hsm.txt pseoperator@192.168.0.123's password: ******** et_hsm.txt | 0 kB | 0.4 kB/s | ETA: 00:00:00 | 100% -
Login to PSESH as pseoperator.
-
If desired, check to ensure that the configuration file was transferred to the appliance.
psesh:>files show
psesh:>files show SCP Folder Content ------------------ total 0.4K 0.4K et_hsm.txt Command Result : 0 (Success) -
Set the etnetserver configuration file. See sysconf etnetcfg for syntax.
psesh:>sysconf etnetcfg set <filename>
psesh:>sysconf etnetcfg set et_hsm.txt WARNING !! This command will modify the settings of the appliance. It could affect client connections, and result in an unusable system. If you are sure that you wish to proceed, then type 'proceed', otherwise type 'quit' > proceed Proceeding... The config file has been set. To apply the changes, please restart etnetserver Command Result : 0 (Success) -
Restart the etnetserver service.
psesh:>service restart etnetserver
-
View the new configuration to confirm the changes.
psesh:>sysconf etnetcfg show
psesh:>sysconf etnetcfg show etnetserver is running Current etnetserver configuration ET_HSM_NETSERVER_OLD_WORKER_COUNT=5 ET_HSM_NETSERVER_V2_WORKER_COUNT=12 ET_HSM_NETSERVER_READ_TIMEOUT_SECS=40 ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS=40 ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT=5 ET_HSM_NETSERVER_FRAG_SIZE=5000 ET_HSM_NETSERVER_ALLOW_RESET=OnHalt ET_HSM_NETSERVER_PORT=12396 ET_HSM_NETSERVER_LOG_CHANNEL=0 ET_HSM_NETSERVER_LOG_NAME=etnetserver ET_HSM_NETSERVER_LOG_LEVEL=0 Command Result : 0 (Success)
Configuration options
This subsection describes available configuration options and modifiable configuration items.
Note
Thales recommends leaving configuration items at the their default value or setting them to a valid value specified in the following table. If the value of a configuration item must be changed and no valid values are given, contact Thales customer support for assistance.
Refer to the following configuration items:
PCI mode client configuration items
Currently, there is only one modifiable configuration item for PCI mode.
- ET_HSM_PCICLIENT_READ_TIMEOUT_SECS
-
Determines the time in seconds the PCI driver will wait before timing out on a read operation. It should be set long enough to avoid an unintentional timeout, which causes the driver to shut down the HSM.
The default timeout should be long enough for general use. The value should only be modified if the client-side application is expected to wait for a longer duration, as in the case of key entry on a PIN pad.
Default=600
Network mode client configuration items
The following client configuration items are available for Network mode.
- ET_HSM_NETCLIENT_HEARTBEAT=[ON|OFF]
-
If ON, net client is to request and support heartbeat messages from the network server.
Default=OFF
- ET_HSM_NETCLIENT_INACTIVITY_PERIOD_SECS
-
Number of seconds of no network activity before a connection is considered inactive.
If heartbeat is enabled, a heartbeat message is sent to the network server after this period expires, to keep the connection alive.
Default=60
- ET_HSM_NETCLIENT_LOG_CHANNEL
-
Channel (destination) to write log entries to. Valid and default values are the following:
0 - Windows Event Log
1 - Standard out
2 - Standard error
Default=0
Valid values are from 0 to 7, inclusive, and map to syslog LOG_LOCAL# values.
Default=0
- ET_HSM_NETCLIENT_LOG_NAME
-
Name of application/context to associate with log entries.
Default=etnetclient
- ET_HSM_NETCLIENT_READ_TIMEOUT_SECS
-
Seconds to allow before timing out a TCP/IP read operation.
Default=300
- ET_HSM_NETCLIENT_SERVERLIST=[host[:port] [host[:port]…]]
-
Space separated list of hosts (with optional port number) to connect to.
Default host=localhost
Default port=12396
IPv6 addresses must be enclosed in square brackets.
- ET_HSM_NETCLIENT_WRITE_TIMEOUT_SECS
-
Seconds to allow before timing out a TCP/IP write operation.
Default=60
- ET_HSM_NETCLIENT_CONNECT_TIMEOUT_SECS
-
Number of seconds before a connection attempt is timed out.
Default=60
- ET_HSM_NETCLIENT_TRACE_DATA=[ON|OFF]
-
If ON, user data will be traced.
Default=OFF
- ET_HSM_NETCLIENT_TRACE_LEVEL
-
The amount of trace to be generated.
Valid values are:
0 - Error only
1 - Include connections status
2 - Include API call flow
Default=0
Network mode server configuration items
The following server configuration items are available for Network mode.
- ET_HSM_NETSERVER_OLD_WORKER_COUNT
-
Number of threads to reserve for processing old ProtectToolkit-C remote client connections.
Default: 3
- ET_HSM_NETSERVER_V2_WORKER_COUNT
-
Number of worker threads, per HSM, to reserve for processing new net client connections.
Default: 10
- ET_HSM_NETSERVER_READ_TIMEOUT_SECS
-
Number of seconds before a connection is timed out in a read operation.
Default: 30
- ET_HSM_NETSERVER_WRITE_TIMEOUT_SECS
-
Number of seconds before a connection is timed out in a write operation.
Default: 30
- ET_HSM_NETSERVER_CONN_TIMEOUT_COUNT
-
Number of inactivity timeouts on a connection that would cause the connection to be closed by the server. Each inactivity timeout period is 60 seconds.
Default: 3
- ET_HSM_NETSERVER_FRAG_SIZE
-
The threshold value, in number of bytes, where output buffers are coalesced together before being sent via TCP. Servers with fast CPUs can keep this number high, and servers with slow CPUs need to keep this number low for best performance. This is an integer configuration item.
Default: 5000
- ET_HSM_NETSERVER_ALLOW_RESET
-
Whether the server will allow the reset command to be issued or not. This is a string configuration item with the following valid values:
Always: Always allow reset
Never: Never allow reset
OnHalt (default): Allow reset only when the HSM is not in normal mode
- ET_HSM_NETSERVER_PORT
-
TCP port number to use.
Default=12396
- ET_HSM_NETSERVER_LOG_CHANNEL
-
Channel (destination) to write log entries to. Values are platform-dependent. Valid and default values are the following:
0 (default): Windows Event Log
1: Standard out
2: Standard error
Valid values are from 0 to 7, inclusive, and map to syslog LOG_LOCAL# values.
Default=0
- ET_HSM_NETSERVER_LOG_NAME
-
Name of application/context to associate with log entries.
Default=etnetserver
- ET_HSM_NETSERVER_LOG_LEVEL
-
Amount of tracing to generate.
Valid values are:
0 (default): Startup and Errors
1: Startup + errors + client connections
Software emulator mode configuration
The software-only variant of ProtectToolkit-C uses the local file system for storing keys and configuration information. By default, the directory C:\cryptoki is used under Windows and $HOME/.cryptoki/cryptoki under Linux. It is possible to use a storage location other than the default location for your system by setting the value of the ET_PTKC_SW_DATAPATH configuration item to that of the path required.
For example, use the following /bin/sh shell commands on a Unix machine to temporarily set the location to /usr/local/cryptoki:
# ET_PTKC_SW_DATAPATH=/usr/local/cryptoki
# export ET_PTKC_SW_DATAPATH
This change can be made at the temporary, user or system levels on both Unix and Windows platforms. Refer to Editing configuration items for further details on how to go about this if required.
Specifying the network server(s)
By default, the net client will attempt to use the local machine as its server. Default values are:
-
Server Name = 127.0.0.1
-
Server Port = 12396
It is necessary to configure the client to use a different host by using the ET_HSM_NETCLIENT_SERVERLIST configuration item. Several servers can also be specified using this configuration item in which case the services from each server will be available seamlessly to the client.
You can use host names, IPv4 addresses, or IPv6 addresses to specify your network servers.
The full syntax for the ET_HSM_NETCLIENT_SERVERLIST configuration item is:
ET_HSM_NETCLIENT_SERVERLIST=server1[:port1] [server2[:port2]]
Example
The following example shows how to to set the net server to the host name ptkc.mydomain.com at the system level on Windows and Unix/Linux.
To set the net server to the host name ptkc.mydomain.com at the system level
-
Locate the registry key:
HKEY_LOCAL_MACHINE\SOFTWARE\SafeNet\HSM\NETCLIENT
-
Assign the value ptkc.mydomain.com to the entry:
ET_HSM_NETCLIENT_SERVERLIST
To set the net server to the host name ptkc.mydomain.com at the system level
-
Open the file: /etc/default/et_hsm
-
Make the entry: et_hsm_netclient_serverlist=ptkc.mydomain.com
Using IPv6 addressing
When specifying a host by its IPv6 address, you must enclose the IPv6 address in square brackets.. All other rules which apply to IPv4 addressing also apply for IPv6 addressing. For example, the following command is valid for a server with an IPv6 address of 2001:db8::221:5eff:fe46:f17e:
export ET_HSM_NETCLIENT_SERVERLIST=[2001:db8::221:5eff:fe46:f17e]
Symbolic server names are also supported and they must be declared in the /etc/hosts and /etc/networks files. For example, if the /etc/hosts file contains the following entry:
2001:db8::221:5eff:fe46:f17e ServerV6
then you can run the following command:
export ET_HSM_NETCLIENT_SERVERLIST=[ServerV6]
Since the interface ports listen for both IPv6 and IPv4, you can specify both IPv4 and IPv6 addresses in the ET_HSM_NETCLIENT_SERVERLIST configuration item, as follows:
export ET_HSM_NETCLIENT_SERVERLIST=[<IPv6_address>] <IPv4_address>…
